Date Handling

To specify how dates are formatted, you use format strings. The following table lists the elements that you use to compose format strings for dates. Date and time formats are affected by locale settings. The following table lists date and time pattern components.

Symbol	Meaning	Example
G	Era designator	AD
y	Year	2017
M	Month in year, number	8
MM	Month in year, number as two digits	08
MMM	Month in year, abbreviated name	Aug
MMMM	Month in year, full name	August
L	Standalone month, number	0
LL	Standalone month, number as two digits	08
LLL	Standalone month, abbreviated name	Aug
LLLL	Standalone month, full name	August
d	Day in month	10
c	Standalone day	10
h	Hour in 12-hour time (1-12)	12
H	Hour in 24-hour time (0-23)	0
m	Minute in hour	30
s	Second in minute	55
S	Fractional second	978
E	Day of week, abbreviated name	Fri
EEEE	Day of week, full name	Friday
D	Day of year	189
a	AM or PM designator	PM
k	Hour of day, in 24-hour time (0-23)	24
K	Hour of day, in 12-hour time (0-11)	0
z	General time zone	-8
Z	Time zone, RFC 822	-800
v	Time zone, generic name	PDT
Q	Quarter	Q3
Single quotation mark (')	Escapes a character or encloses a string	'o''clock', 'Date='

The following table lists ICU date and time skeleton components. These components can be combined to create an ICU dateFormat skeleton that you can use to format DateTime values.

String	Meaning	Example (en_US locale)
d	Day	24
E	Day of week	Thu
EEEE	Day of week	Thursday
LLL	Standalone month	Aug
LLLL	Standalone month	August
M	Month	8
Md	Month and day	8/24
MEd	Month, day, and day of week	Thu, 8/24
MMM	Month	Aug
MMMd	Month and day	Aug 24
MMMEd	Month, day, and day of week	Thu, Aug 24
MMMM	Month	August
MMMMd	Month and day	August 24
MMMMEEEEd	Month, day, and day of week	Thursday, August 24
QQQ	Quarter	Q3
QQQQ	Quarter	3rd quarter
y	Year	2015
yM	Year and month	8/2017
yMd	Year, month, and day	8/1/2017
yMEd	Year, month, day, and day of week	Thu, 8/24/2017
yMMM	Year and month	Aug 2017
yMMMd	Year, month, and day	August 1, 2017
yMMMEd	Year, month, day, and day of week	Thu, Aug 24, 2017
yMMMM	Year and month	August 2017
yMMMMd	Year, month, and day	August 24, 2017
yMMMMEEEEd	Year, month, day, and day of week	Thursday, August 24, 2017
yQQQ	Year and quarter	Q3 2017
yQQQQ	Year and quarter	3rd quarter 2017
H	Hour in day (24-hour time)	15
Hm	Hour and minute (24-hour time)	15:38
Hms	Hour, minute, and second (24-hour time)	15:38:00
j	Hour (12-hour time)	3 PM
jm	Hour and minute (12-hour time)	3:38 PM
jms	Hour, minute, and second (12-hour time)	3:38:00 PM
m	Minute	38
ms	Minute and second	38:00
s	Second	0

DateTime Functions

Function	Description and Example
new DateTime()	Returns a DateTime object that is initialized with the current date and time. The following function returns a year, such as 2017. new DateTime().year;
new DateTime(millisecondsSinceEpoch)	Returns a DateTime object that is initialized with the specified value. The following function returns 1969-12-31T16:00:00.000. new DateTime(0);
new DateTime(dateString)	Returns a DateTime object that is initialized with the parsed date and time string. The following function returns 2017-02-27T13:27:00.000. new DateTime('2017-02-27 13:27:00');
new DateTime(y,m,d,h,m,s,ms)	Returns a DateTime object that is initialized with the specified values. The following function returns 2017-01-01 00:00:00.000. new DateTime(2017,1,1,0,0,0,0);
day	Returns a day of the month. The following function returns 1. new DateTime(2017,1,1).day;
month	Returns a month of the year. January is represented as 1. The following function returns 2. new DateTime('2017-02-27 13:27:00').month;
year	Returns a year. The following function returns a year, such as 2016. new DateTime().year;
hour	Returns an hour. The following function returns 13. new DateTime('2017-02-27 13:27:00').hour;
minute	Returns a minute. The following function returns 27. new DateTime('2017-02-27 13:27:00').minute;
second	Returns a second. The following function returns 0. new DateTime('2017-02-27 13:27:00').second;
millisecond	Returns a millisecond. The following function returns 798. new DateTime('2017-01-01T13:27:00.798').millisecond;
millisecondsSinceEpoch	Returns the milliseconds since the start of the Unix epoch. The following function returns the millisecondsSinceEpoch, such as 1466113382710. new DateTime().millisecondsSinceEpoch;
weekday	Returns a day of the week. Monday is represented as 1, and Sunday is represented as 7. The following function returns the weekday, such as 4. new DateTime().weekday;
isUtc	Returns whether the date is UTC. The following function returns false. new DateTime(2017,1,1).isUtc;
dateNow()	Returns the millisecondsSinceEpoch of the current date and time. The following function returns the millisecondsSinceEpoch, such as 1466113699717. dateNow();
dateParse(str)	Parses a date from a string and then returns int(millisecondsSinceEpoch) of that date. dateParse supports a super-set of formats supported by DateTime(dateString). The following function returns 1293868800000. dateParse('1/1/2011');
dateFormat(date, dateFormat)	Parses date string or uses millisecondsSinceEpoch and returns the string in the specified dateFormat. The following function returns a string, such as 06/2016. dateFormat(dateNow(),"MM/yyyy");

DateTime Function Examples

The following example finds the number of days in the previous month.

dt = new DateTime();
lastMonth = new DateTime(dt.year,dt.month, 0, dt.hour, dt.minute, dt.second, dt.millisecond);
print (lastMonth.day);

The following example returns the most recent Sunday before the current date.

dt = new DateTime(); 
lastSunday = new DateTime(dt.year, dt.month, dt.day - dt.weekday);